Administration of Lookup Lists: lutserver & emulutsrebuild

In this example a user changes the city value in a record from Bendigo to Sandhurst and saves the record. The following steps occur:

1. When the user saves the record, the EMu server generates an XML description of the changes made to the record. The Audit Server (auditserver) loads these changes and passes them on to all registered plugins. The Lookup List Services registers the Lookup List Audit Plugin when the Audit Server is started. For our example record, the changes will show that Bendigo was changed to Sandhurst in the City column.
2. The Lookup List Audit Plugin looks at the changes supplied by the Audit Server. For each column changed it checks to see if a Lookup List is associated with the column. For our example, it will determine that the City column is associated with the Location Lookup List. It will then look at the two values and their associated operations. The value Bendigo has a delete operation (since it is being removed) and the value Sandhurst has an insert operation (as it is the new value). Since the Windows client was used to save the record, the Audit Plugin will ignore the insert operation as the user will have been asked to add the new entry to the Location Lookup List if it did not exist already. The delete operation is passed to the Lookup List Server for processing.
3. The Lookup List Audit Plugin writes a file containing the:
   • Operation performed (delete)
   • Value deleted (Bendigo)
   • Lookup List Name (Location)
   • Column changed (City)

   The file is located in the loads/luts/data directory. The format of the file name is date.time.table.irn, where:

   • date is an eight digit date in yyyymmdd format.
   • time is a six digit time in hhmmss format.
   • Table is the database table in which the record was modified.
   • irn is the key number of the record modified.

   An example file name is: 20121026.133308.ecatalogue.375.

4. The Lookup List Server fetches all files in the loads/luts/data directory and sorts them into date/time order. It is important that the files are processed in the same order as they were created, otherwise synchronisation issues may arise. The Lookup List Server reads the contents of each file, extracting the information within. Then for each Lookup List in the file it determines the operation to apply (insert or delete):
   • For an insert operation it checks to see if the value is already in the Lookup List; if not, it inserts a new value into the eluts table.
   • For a delete operation it checks whether the value is used anywhere in the EMu system for the given Lookup List name. If the value is not used, the record is deleted from the eluts table (provided it is not Persistent).

   Once the file has been processed, it is removed. Once all the files have been processed, the Lookup List Server waits for new files to process.

The reason for so many steps is that audit plugins must be fast so that the Audit Server can process audit records quickly. To ensure the audit plugin is fast, the main Lookup List processing is removed from the audit plugin and moved to the Lookup List Server. The split ensures that the Audit Server keeps up with audit changes, even when the Lookup List Server may lag.

The Lookup List Server handles all deletion operations, that is it checks whether a Lookup List entry is still in use and if not, deletes it. It also handles insertions (that is new values) from all sources except the Windows client.

The Lookup List Server complies with the Lookup Registry entry and Lookup Exact Registry entry:

• If a column has Lookup Exact set to true, then all comparisons with existing entries in the Lookup List table are performed as exact matches, i.e. the character case and punctuation must match exactly.
• If Lookup Exact is not enabled, all punctuation and character case is ignored for value comparisons.

The Lookup Registry entry is used to control the flags set when adding new values to a Lookup List. The table below lists each setting and examines how the Lookup List Server implements the required functionality. The Lookup Registry entry settings are generally set on a per column basis.

Finally, the Lookup List Server will not delete any entry from the Lookup List table that has Persistent enabled.

The Lookup List Server, lutserver, provides the functionality required to keep the Lookup List table in sync with values used within the EMu System. The addition of the server removes the need to rebuild the Lookup List tables on a nightly (or otherwise) basis.

The Luts directory is a directory on the EMu server. It contains text files with default values for specific Lookup Lists. During the Rebuild Lookup Lists process, all values in these text files are added to their respective Lookup Lists.

The text files in the Luts directory can be used to import multiple values such as locations and / or post codes into a Lookup List. These values will be added to the Lookup List irrespective of data in that field in the table.

The command used to rebuild all Lookup Lists is:

emulutsrebuild -t

It should not be necessary to run this command. The Lookup List Server maintains Lookup List synchronisation. The command may be used to ensure the Lookup List table is synchronised correctly.

The command used to check whether the Lookup List table is synchronised is:

emulutsrebuild -d -t -v

This command runs the data generation phase only. The Lookup List table is not modified. The verbose option prints out any inconsistencies found.

The command used to rebuild the Location and Admin Names Lookup Lists is:

emulutsrebuild Location 'Admin Names'

This command rebuilds the Location and Admin Names Lookup Lists. As the -t option is not specified, any entries in text files will not be loaded.

Note: Note the use of single quotes to enclose the names of Lookup Lists that contain spaces.